remark

What is remark?

The remark npm package is a powerful, extensible Markdown processor built on the unified collective ecosystem. It allows for parsing, transforming, and compiling Markdown content with a focus on syntax trees. Remark can be used for a variety of tasks such as linting Markdown, transforming the syntax for different purposes, or extracting metadata from documents.

What are remark's main functionalities?

Parsing Markdown to Syntax Trees

This feature allows users to parse Markdown content into an abstract syntax tree (AST), enabling programmatic analysis and manipulation of the content.

const remark = require('remark');
const markdown = 'Some **Markdown** text.';
remark().parse(markdown);

Transforming Syntax Trees

With this feature, users can transform the syntax tree generated from Markdown content. For example, converting the tree to HTML by using the remark-html plugin.

const remark = require('remark');
const html = require('remark-html');
const markdown = 'Some **Markdown** text.';
remark().use(html).processSync(markdown).toString();

Linting Markdown

This feature enables users to lint their Markdown content for style and syntax issues, ensuring consistency and quality in their Markdown files.

const remark = require('remark');
const recommended = require('remark-preset-lint-recommended');
const report = require('vfile-reporter');

remark().use(recommended).process('_Emphasis_ and **importance**', (err, file) => {
  console.error(report(err || file));
});

Other packages similar to remark

markdown-it

markdown-it is a fast and extensible Markdown parser that can render HTML. It is similar to remark in its extensibility but focuses more on speed and adherence to the CommonMark specification without an emphasis on abstract syntax trees.

showdown

showdown is another Markdown to HTML converter that can run both in the browser and on the server. Unlike remark, which is built around a plugin ecosystem and AST manipulation, showdown focuses on configurability and extension through a different type of extension mechanism.

marked

marked is a low-level Markdown compiler for parsing Markdown without caching or blocking for files. It is designed for speed and is simpler in scope compared to remark, which offers a broader range of processing capabilities through its plugins and unified ecosystem.

README

remark recently changed its name from mdast. Read more about what changed and how to migrate »

remark is a markdown processor powered by plugins. Lots of tests. Node, io.js, and the browser. 100% coverage.

remark is not just another markdown to HTML compiler. It can generate, and reformat, markdown too. It is powered by plugins to do all kinds of things: validate your markdown, add links for GitHub references, or add a table of contents.

The project contains both an extensive JavaScript API for parsing, modifying, and compiling markdown, and a friendly Command Line Interface making it easy to validate, prepare, and compile markdown in a build step.

Table of Contents

• Installation

• Usage

• API

  • remark.process(value[, options][, done])
  • remark.use(plugin[, options])

• CLI

• License

Installation

npm:

npm install remark

Read more about alternative ways to install and use »

Usage

Load dependencies:

var remark = require('remark');
var html = require('remark-html');
var yamlConfig = require('remark-yaml-config');

Use plugins:

var processor = remark().use(yamlConfig).use(html);

Process the document:

var doc = processor.process([
    '---',
    'remark:',
    '  commonmark: true',
    '---',
    '',
    '2) Some *emphasis*, **strongness**, and `code`.'
].join('\n'));

Yields:

<ol start="2">
<li>Some <em>emphasis</em>, <strong>strongness</strong>, and <code>code</code>.</li>
</ol>

API

Get Started with the API »

remark.process(value[, options][, done])

Parse a markdown document, apply plugins to it, and compile it into something else.

Signatures

• doc = remark.process(value, options?, done?).

Parameters

• value (string) — Markdown document;

• options (Object) — Settings:

  • gfm (boolean, default: true) — See GitHub Flavoured Markdown;
  • yaml (boolean, default: true) — See YAML;
  • commonmark (boolean, default: false) — See CommonMark;
  • footnotes (boolean, default: false) — See Footnotes;
  • pedantic (boolean, default: false) — See Pedantic;
  • breaks (boolean, default: false) — See Breaks;
  • entities (boolean, default: false) — See Encoding Entities;
  • setext (boolean, default: false) — See Setext Headings;
  • closeAtx (boolean, default: false) — See Closed ATX Headings;
  • looseTable (boolean, default: false) — See Loose Tables;
  • spacedTable (boolean, default: true) — See Spaced Tables;
  • fence ("~" or "`", default: "`") — See Fence;
  • fences (boolean, default: false) — See Fences;
  • bullet ("-", "*", or "+", default: "-") — See List Item Bullets;
  • listItemIndent ("tab", "mixed" or "1", default: "tab") — See List Item Indent;
  • incrementListMarker (boolean, default: true) — See List Marker Increase;
  • rule ("-", "*", or "_", default: "*") — See Horizontal Rules;
  • ruleRepetition (number, default: 3) — See Horizontal Rules;
  • ruleSpaces (boolean, default true) — See Horizontal Rules;
  • strong ("_", or "*", default "*") — See Emphasis Markers;
  • emphasis ("_", or "*", default "_") — See Emphasis Markers.
  • position (boolean, default: true) — See Position;

• done (function(Error?, string?)) — Callback invoked when the output is generated with either an error, or a result. Only strictly needed when asynchronous plugins are used.

All options (including the options object itself) can be null or undefined to default to their default values.

Returns

string or null: A document. Formatted in markdown by default, or in whatever a plugin generates. The result is null if a plugin is asynchronous, in which case the callback done should’ve been passed (do not worry: plugin creators make sure you know its asynchronous).

remark.use(plugin[, options])

Change the way remark works by using a plugin.

Signatures

• processor = remark.use(plugin, options?);
• processor = remark.use(plugins).

Parameters

• plugin (Function) — A Plugin;
• plugins (Array.<Function>) — A list of Plugins;
• options (Object?) — Passed to plugin. Specified by its documentation.

Returns

Object: an instance of Remark: The returned object functions just like remark (it has the same methods), but caches the used plugins. This provides the ability to chain use calls to use multiple plugins, but ensures the functioning of the remark module does not change for other dependents.

CLI

Get Started with the CLI »

Install:

npm install --global remark

Use:

Usage: remark [options] <pathspec...>

Markdown processor powered by plugins

Options:

  -h, --help                output usage information
  -V, --version             output the version number
  -o, --output [path]       specify output location
  -c, --config-path <path>  specify configuration location
  -i, --ignore-path <path>  specify ignore location
  -s, --setting <settings>  specify settings
  -u, --use <plugins>       use transform plugin(s)
  -e, --ext <extensions>    specify extensions
  -w, --watch               watch for changes and reprocess
  -a, --ast                 output AST information
  -q, --quiet               output only warnings and errors
  -S, --silent              output only errors
  -f, --frail               exit with 1 on warnings
  --file-path <path>        specify file path to process as
  --no-stdout               disable writing to stdout
  --no-color                disable color in output
  --no-rc                   disable configuration from .remarkrc
  --no-ignore               disable ignore from .remarkignore

See also: man 1 remark, man 3 remark,
  man 3 remarkplugin, man 5 remarkrc,
  man 5 remarkignore, man 7 remarksetting,
  man 7 remarkconfig, man 7 remarkplugin.

Examples:

  # Process `readme.md`
  $ remark readme.md -o readme-new.md

  # Pass stdin(4) through remark, with settings, to stdout(4)
  $ remark --setting "setext: true, bullet: \"*\"" < readme.md > readme-new.md

  # Use a plugin (with options)
  $ npm install remark-toc
  $ remark readme.md --use "toc=heading:\"contents\"" -o

  # Rewrite markdown in a directory
  $ remark . -o

License

MIT © Titus Wormer

This project was initially a fork of marked.

Copyright (c) 2011-2014, Christopher Jeffrey. (MIT License)